2. EL 9
  3. tcl-doc
  4. clock(n)

Scroll to navigation

clock(n) Tcl Built-In Commands clock(n) 





NAME


clock - Obtain and manipulate dates and times






SYNOPSIS


package require Tcl 8.5


clock add timeVal ?count unit...? ?-option
    value?


clock clicks ?-option?


clock format timeVal ?-option value...?


clock microseconds


clock milliseconds


clock scan inputString ?-option value...?


clock seconds










DESCRIPTION


The clock command performs several operations that obtain
    and manipulate values that represent times. The command supports several
    subcommands that determine what action is carried out by the command.



  

  
Adds a (possibly negative) offset to a time that is expressed as an
      integer number of seconds. See CLOCK ARITHMETIC for a full
      description.

  

  
If no -option argument is supplied, returns a high-resolution time
      value as a system-dependent integer value. The unit of the value is
      system-dependent but should be the highest resolution clock available on
      the system such as a CPU cycle counter. See HIGH RESOLUTION TIMERS
      for a full description.






If the -option argument is -milliseconds, then the
    command is synonymous with clock milliseconds (see below). This usage
    is obsolete, and clock milliseconds is to be considered the preferred
    way of obtaining a count of milliseconds.


If the -option argument is -microseconds, then the
    command is synonymous with clock microseconds (see below). This usage
    is obsolete, and clock microseconds is to be considered the preferred
    way of obtaining a count of microseconds.





  

  
Formats a time that is expressed as an integer number of seconds into a
      format intended for consumption by users or external programs. See
      FORMATTING TIMES for a full description.

  

  
Returns the current time as an integer number of microseconds. See HIGH
      RESOLUTION TIMERS for a full description.

  

  
Returns the current time as an integer number of milliseconds. See HIGH
      RESOLUTION TIMERS for a full description.

  

  
Scans a time that is expressed as a character string and produces an
      integer number of seconds. See SCANNING TIMES for a full
      description.

  

  
Returns the current time as an integer number of seconds.






PARAMETERS



  

  
An integer representing a count of some unit of time. See CLOCK
      ARITHMETIC for the details.

  

  
An integer value passed to the clock command that represents an
      absolute time as a number of seconds from the epoch time of 1
      January 1970, 00:00 UTC. Note that the count of seconds does not include
      any leap seconds; seconds are counted as if each UTC day has exactly 86400
      seconds. Tcl responds to leap seconds by speeding or slowing its clock by
      a tiny fraction for some minutes until it is back in sync with UTC; its
      data model does not represent minutes that have 59 or 61 seconds.

  

  
One of the words, seconds, minutes, hours,
      days, weeks, months, or years, or any unique
      prefix of such a word. Used in conjunction with count to identify
      an interval of time, for example, 3 seconds or 1 year.








OPTIONS



  

  
Specifies that any relative times present in a clock scan command
      are to be given relative to time. time must be expressed as
      a count of nominal seconds from the epoch time of 1 January 1970, 00:00
      UTC.

  

  
Specifies the desired output format for clock format or the
      expected input format for clock scan. The format string
      consists of any number of characters other than the per-cent sign
      (“%”) interspersed with any number of format
      groups, which are two-character sequences beginning with the per-cent
      sign. The permissible format groups, and their interpretation, are
      described under FORMAT GROUPS.






On clock format, the default format is






%a %b %d %H:%M:%S %Z %Y




On clock scan, the lack of a -format option
    indicates that a “free format scan” is requested; see FREE
    FORM SCAN for a description of what happens.





  

  
If boolean is true, specifies that a time specified to clock
      add, clock format or clock scan should be processed in
      UTC. If boolean is false, the processing defaults to the local time
      zone. This usage is obsolete; the correct current usage is to specify the
      UTC time zone with “-timezone :UTC” or any of
      the equivalent ways to specify it.

  

  
Specifies that locale-dependent scanning and formatting (and date
      arithmetic for dates preceding the adoption of the Gregorian calendar) is
      to be done in the locale identified by localeName. The locale name
      may be any of the locales acceptable to the msgcat package, or it
      may be the special name system, which represents the current locale
      of the process, or the null string, which represents Tcl's default
    locale.






The effect of locale on scanning and formatting is discussed in
    the descriptions of the individual format groups under FORMAT GROUPS.
    The effect of locale on clock arithmetic is discussed under CLOCK
    ARITHMETIC.





  

  
Specifies that clock arithmetic, formatting, and scanning are to be done
      according to the rules for the time zone specified by zoneName. The
      permissible values, and their interpretation, are discussed under TIME
      ZONES. On subcommands that expect a -timezone argument, the
      default is to use the current time zone. The current time zone is
      determined, in order of preference, by:







  
[1]

  
the environment variable TCL_TZ.

  
[2]

  
the environment variable TZ.

  
[3]

  
on Windows systems, the time zone settings from the Control Panel.






If none of these is present, the C localtime and
    mktime functions are used to attempt to convert times between local
    and Greenwich. On 32-bit systems, this approach is likely to have bugs,
    particularly for times that lie outside the window (approximately the years
    1902 to 2037) that can be represented in a 32-bit integer.








CLOCK ARITHMETIC


The clock add command performs clock arithmetic on a value
    (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00
    UTC) given as its first argument. The remaining arguments (other than the
    possible -timezone, -locale and -gmt options) are
    integers and keywords in alternation, where the keywords are chosen from
    seconds, minutes, hours, days, weeks,
    months, or years, or any unique prefix of such a word.


Addition of seconds, minutes and hours is fairly straightforward;
    the given time increment (times sixty for minutes, or 3600 for hours) is
    simply added to the timeVal given to the clock add command.
    The result is interpreted as a nominal number of seconds from the Epoch.


Surprising results may be obtained when crossing a point at which
    a leap second is inserted or removed; the clock add command simply
    ignores leap seconds and therefore assumes that times come in sequence,
    23:59:58, 23:59:59, 00:00:00. (This assumption is handled by the fact that
    Tcl's model of time reacts to leap seconds by speeding or slowing the clock
    by a minuscule amount until Tcl's time is back in step with the world.


The fact that adding and subtracting hours is defined in terms of
    absolute time means that it will add fixed amounts of time in time zones
    that observe summer time (Daylight Saving Time). For example, the following
    code sets the value of x to 04:00:00 because the clock has
    changed in the interval in question.






set s [clock scan {2004-10-30 05:00:00} \


           -format {%Y-%m-%d %H:%M:%S} \


           -timezone :America/New_York]
set a [clock add $s 24 hours -timezone :America/New_York]
set x [clock format $a \


           -format {%H:%M:%S} -timezone :America/New_York]




Adding and subtracting days and weeks is accomplished by
    converting the given time to a calendar day and time of day in the
    appropriate time zone and locale. The requisite number of days (weeks are
    converted to days by multiplying by seven) is added to the calendar day, and
    the date and time are then converted back to a count of seconds from the
    epoch time.


Adding and subtracting a given number of days across the point
    that the time changes at the start or end of summer time (Daylight Saving
    Time) results in the same local time on the day in question. For
    instance, the following code sets the value of x to
  05:00:00.






set s [clock scan {2004-10-30 05:00:00} \


           -format {%Y-%m-%d %H:%M:%S} \


           -timezone :America/New_York]
set a [clock add $s 1 day -timezone :America/New_York]
set x [clock format $a \


           -format {%H:%M:%S} -timezone :America/New_York]




In cases of ambiguity, where the same local time happens twice on
    the same day, the earlier time is used. In cases where the conversion yields
    an impossible time (for instance, 02:30 during the Spring Daylight Saving
    Time change using US rules), the time is converted as if the clock had not
    changed. Thus, the following code will set the value of x to
    03:30:00.






set s [clock scan {2004-04-03 02:30:00} \


           -format {%Y-%m-%d %H:%M:%S} \


           -timezone :America/New_York]
set a [clock add $s 1 day -timezone :America/New_York]
set x [clock format $a \


           -format {%H:%M:%S} -timezone :America/New_York]




Adding a given number of days or weeks works correctly across the
    conversion between the Julian and Gregorian calendars; the omitted days are
    skipped. The following code sets z to 1752-09-14.






set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [clock add $x 1 day -locale en_US]
set z [clock format $y -format %Y-%m-%d -locale en_US]




In the bizarre case that adding the given number of days yields a
    date that does not exist because it falls within the dropped days of the
    Julian-to-Gregorian conversion, the date is converted as if it was on the
    Julian calendar.


Adding a number of months, or a number of years, is similar; it
    converts the given time to a calendar date and time of day. It then adds the
    requisite number of months or years, and reconverts the resulting date and
    time of day to an absolute time.


If the resulting date is impossible because the month has too few
    days (for example, when adding 1 month to 31 January), the last day of the
    month is substituted. Thus, adding 1 month to 31 January will result in 28
    February in a common year or 29 February in a leap year.


The rules for handling anomalies relating to summer time and to
    the Gregorian calendar are the same when adding/subtracting months and years
    as they are when adding/subtracting days and weeks.


If multiple count unit pairs are present on the command,
    they are evaluated consecutively, from left to right.






HIGH RESOLUTION TIMERS


Most of the subcommands supported by the clock command deal
    with times represented as a count of seconds from the epoch time, and this
    is the representation that clock seconds returns. There are three
    exceptions, which are all intended for use where higher-resolution times are
    required. clock milliseconds returns the count of milliseconds from
    the epoch time, and clock microseconds returns the count of
    microseconds from the epoch time. In addition, there is a clock
    clicks command that returns a platform-dependent high-resolution timer.
    Unlike clock seconds and clock milliseconds, the value of
    clock clicks is not guaranteed to be tied to any fixed epoch; it is
    simply intended to be the most precise interval timer available, and is
    intended only for relative timing studies such as benchmarks.






FORMATTING TIMES


The clock format command produces times for display to a
    user or writing to an external medium. The command accepts times that are
    expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, as
    returned by clock seconds, clock scan, clock add,
    file atime or file mtime.


If a -format option is present, the following argument is a
    string that specifies how the date and time are to be formatted. The string
    consists of any number of characters other than the per-cent sign
    (“%”) interspersed with any number of format
    groups, which are two-character sequences beginning with the per-cent
    sign. The permissible format groups, and their interpretation, are described
    under FORMAT GROUPS.


If a -timezone option is present, the following argument is
    a string that specifies the time zone in which the date and time are to be
    formatted. As an alternative to “-timezone
    :UTC”, the obsolete usage “-gmt
    true” may be used. See TIME ZONES for the permissible
    variants for the time zone.


If a -locale option is present, the following argument is a
    string that specifies the locale in which the time is to be formatted, in
    the same format that is used for the msgcat package. Note that the
    default, if -locale is not specified, is the root locale {}
    rather than the current locale. The current locale may be obtained by using
    -locale current. In addition, some platforms support a
    system locale that reflects the user's current choices. For instance,
    on Windows, the format that the user has selected from dates and times in
    the Control Panel can be obtained by using the system locale. On
    platforms that do not define a user selection of date and time formats
    separate from LC_TIME, -locale system is synonymous
    with -locale current.






SCANNING TIMES


The clock scan command accepts times that are formatted as
    strings and converts them to counts of seconds from the epoch time of 1
    January 1970, 00:00 UTC. It normally takes a -format option that is
    followed by a string describing the expected format of the input. (See
    FREE FORM SCAN for the effect of clock scan without such an
    argument.) The string consists of any number of characters other than the
    per-cent sign (“%”), interspersed with any number of
    format groups, which are two-character sequences beginning with the
    per-cent sign. The permissible format groups, and their interpretation, are
    described under FORMAT GROUPS.


If a -timezone option is present, the following argument is
    a string that specifies the time zone in which the date and time are to be
    interpreted. As an alternative to -timezone :UTC, the obsolete
    usage -gmt true may be used. See TIME ZONES for the
    permissible variants for the time zone.


If a -locale option is present, the following argument is a
    string that specifies the locale in which the time is to be interpreted, in
    the same format that is used for the msgcat package. Note that the
    default, if -locale is not specified, is the root locale {}
    rather than the current locale. The current locale may be obtained by using
    -locale current. In addition, some platforms support a
    system locale that reflects the user's current choices. For instance,
    on Windows, the format that the user has selected from dates and times in
    the Control Panel can be obtained by using the system locale. On
    platforms that do not define a user selection of date and time formats
    separate from LC_TIME, -locale system is synonymous
    with -locale current.


If a -base option is present, the following argument is a
    time (expressed in seconds from the epoch time) that is used as a base
    time for interpreting relative times. If no -base option is
    present, the base time is the current time.


Scanning of times in fixed format works by determining three
    things: the date, the time of day, and the time zone. These three are then
    combined into a point in time, which is returned as the number of seconds
    from the epoch.


Before scanning begins, the format string is preprocessed to
    replace %c, %Ec, %x, %Ex, %X. %Ex,
    %r, %R, %T, %D, %EY and %+ format
    groups with counterparts that are appropriate to the current locale and
    contain none of the above groups. For instance, %D will (in the
    en_US locale) be replaced with %m/%d/%Y.


The date is determined according to the fields that are present in
    the preprocessed format string. In order of preference:



  
[1]

  
If the string contains a %s format group, representing seconds from
      the epoch, that group is used to determine the date.

  
[2]

  
If the string contains a %J format group, representing the Julian
      Day Number, that group is used to determine the date.

  
[3]

  
If the string contains a complete set of format groups specifying century,
      year, month, and day of month; century, year, and day of year; or ISO8601
      fiscal year, week of year, and day of week; those groups are combined and
      used to determine the date. If more than one complete set is present, the
      one at the rightmost position in the string is used.

  
[4]

  
If the string lacks a century but contains a set of format groups
      specifying year of century, month and day of month; year of century and
      day of year; or two-digit ISO8601 fiscal year, week of year, and day of
      week; those groups are combined and used to determine the date. If more
      than one complete set is present, the one at the rightmost position in the
      string is used. The year is presumed to lie in the range 1938 to 2037
      inclusive.

  
[5]

  
If the string entirely lacks any specification for the year (or contains
      the year only on the locale's alternative calendar) and contains a set of
      format groups specifying month and day of month, day of year, or week of
      year and day of week, those groups are combined and used to determine the
      date. If more than one complete set is present, the one at the rightmost
      position in the string is used. The year is determined by interpreting the
      base time in the given time zone.

  
[6]

  
If the string contains none of the above sets, but has a day of the month
      or day of the week, the day of the month or day of the week are used to
      determine the date by interpreting the base time in the given time zone
      and returning the given day of the current week or month. (The week runs
      from Monday to Sunday, ISO8601-fashion.) If both day of month and day of
      week are present, the day of the month takes priority.

  
[7]

  
If none of the above rules results in a usable date, the date of the base
      time in the given time zone is used.




The time is also determined according to the fields that are
    present in the preprocessed format string. In order of preference:



  
[1]

  
If the string contains a %s format group, representing seconds from
      the epoch, that group determines the time of day.

  
[2]

  
If the string contains either an hour on the 24-hour clock or an hour on
      the 12-hour clock plus an AM/PM indicator, that hour determines the hour
      of the day. If the string further contains a group specifying the minute
      of the hour, that group combines with the hour. If the string further
      contains a group specifying the second of the minute, that group combines
      with the hour and minute.

  
[3]

  
If the string contains neither a %s format group nor a group
      specifying the hour of the day, then midnight (00:00, the start of
      the given date) is used. The time zone is determined by either the
      -timezone or -gmt options, or by using the current time
      zone.




If a format string lacks a %z or %Z format group, it
    is possible for the time to be ambiguous because it appears twice in the
    same day, once without and once with Daylight Saving Time. If this situation
    occurs, the first occurrence of the time is chosen. (For this reason, it is
    wise to have the input string contain the time zone when converting local
    times. This caveat does not apply to UTC times.)


If the interpretation of the groups yields an impossible time
    because a field is out of range, enough of that field's unit will be added
    to or subtracted from the time to bring it in range. Thus, if attempting to
    scan or format day 0 of the month, one day will be subtracted from day 1 of
    the month, yielding the last day of the previous month.


If the interpretation of the groups yields an impossible time
    because a Daylight Saving Time change skips over that time, or an ambiguous
    time because a Daylight Saving Time change skips back so that the clock
    observes the given time twice, and no time zone specifier (%z or
    %Z) is present in the format, the time is interpreted as if the clock
    had not changed.






FORMAT GROUPS


The following format groups are recognized by the clock
    scan and clock format commands.



  
%a

  
On output, receives an abbreviation (e.g., Mon) for the day
      of the week in the given locale. On input, matches the name of the day of
      the week in the given locale (in either abbreviated or full form, or any
      unique prefix of either form).

  
%A

  
On output, receives the full name (e.g., Monday) of the day
      of the week in the given locale. On input, matches the name of the day of
      the week in the given locale (in either abbreviated or full form, or any
      unique prefix of either form).

  
%b

  
On output, receives an abbreviation (e.g., Jan) for the name
      of the month in the given locale. On input, matches the name of the month
      in the given locale (in either abbreviated or full form, or any unique
      prefix of either form).

  
%B

  
On output, receives the full name (e.g., January) of the
      month in the given locale. On input, matches the name of the month in the
      given locale (in either abbreviated or full form, or any unique prefix of
      either form).

  
%c

  
On output, receives a localized representation of date and time of day;
      the localized representation is expected to use the Gregorian calendar. On
      input, matches whatever %c produces.

  
%C

  
On output, receives the number of the century in Indo-Arabic numerals. On
      input, matches one or two digits, possibly with leading whitespace, that
      are expected to be the number of the century.

  
%d

  
On output, produces the number of the day of the month, as two decimal
      digits. On input, matches one or two digits, possibly with leading
      whitespace, that are expected to be the number of the day of the
    month.

  
%D

  
This format group is synonymous with %m/%d/%Y. It should be used
      only in exchanging data within the en_US locale, since other
      locales typically do not use this order for the fields of the date.

  
%e

  
On output, produces the number of the day of the month, as one or two
      decimal digits (with a leading blank for one-digit dates). On input,
      matches one or two digits, possibly with leading whitespace, that are
      expected to be the number of the day of the month.

  
%Ec

  
On output, produces a locale-dependent representation of the date and time
      of day in the locale's alternative calendar. On input, matches whatever
      %Ec produces. The locale's alternative calendar need not be the
      Gregorian calendar.

  
%EC

  
On output, produces a locale-dependent name of an era in the locale's
      alternative calendar. On input, matches the name of the era or any unique
      prefix.

  
%EE

  
On output, produces the string B.C.E. or C.E., or a string
      of the same meaning in the locale, to indicate whether %Y refers to
      years before or after Year 1 of the Common Era. On input, accepts the
      string B.C.E., B.C., C.E., A.D., or the
      abbreviation appropriate to the current locale, and uses it to fix whether
      %Y refers to years before or after Year 1 of the Common Era.

  
%Ex

  
On output, produces a locale-dependent representation of the date in the
      locale's alternative calendar. On input, matches whatever %Ex
      produces. The locale's alternative calendar need not be the Gregorian
      calendar.

  
%EX

  
On output, produces a locale-dependent representation of the time of day
      in the locale's alternative numerals. On input, matches whatever
      %EX produces.

  
%Ey

  
On output, produces a locale-dependent number of the year of the era in
      the locale's alternative calendar and numerals. On input, matches such a
      number.

  
%EY

  
On output, produces a representation of the year in the locale's
      alternative calendar and numerals. On input, matches what %EY
      produces. Often synonymous with %EC%Ey.

  
%g

  
On output, produces a two-digit year number suitable for use with the
      week-based ISO8601 calendar; that is, the year number corresponds to the
      week number produced by %V. On input, accepts such a two-digit year
      number, possibly with leading whitespace.

  
%G

  
On output, produces a four-digit year number suitable for use with the
      week-based ISO8601 calendar; that is, the year number corresponds to the
      week number produced by %V. On input, accepts such a four-digit
      year number, possibly with leading whitespace.

  
%h

  
This format group is synonymous with %b.

  
%H

  
On output, produces a two-digit number giving the hour of the day (00-23)
      on a 24-hour clock. On input, accepts such a number.

  
%I

  
On output, produces a two-digit number giving the hour of the day (12-11)
      on a 12-hour clock. On input, accepts such a number.

  
%j

  
On output, produces a three-digit number giving the day of the year
      (001-366). On input, accepts such a number.

  
%J

  
On output, produces a string of digits giving the Julian Day Number. On
      input, accepts a string of digits and interprets it as a Julian Day
      Number. The Julian Day Number is a count of the number of calendar days
      that have elapsed since 1 January, 4713 BCE of the proleptic Julian
      calendar. The epoch time of 1 January 1970 corresponds to Julian Day
      Number 2440588.

  
%k

  
On output, produces a one- or two-digit number giving the hour of the day
      (0-23) on a 24-hour clock. On input, accepts such a number.

  
%l

  
On output, produces a one- or two-digit number giving the hour of the day
      (12-11) on a 12-hour clock. On input, accepts such a number.

  
%m

  
On output, produces the number of the month (01-12) with exactly two
      digits. On input, accepts two digits and interprets them as the number of
      the month.

  
%M

  
On output, produces the number of the minute of the hour (00-59) with
      exactly two digits. On input, accepts two digits and interprets them as
      the number of the minute of the hour.

  
%N

  
On output, produces the number of the month (1-12) with one or two digits,
      and a leading blank for one-digit dates. On input, accepts one or two
      digits, possibly with leading whitespace, and interprets them as the
      number of the month.

  
%Od, %Oe, %OH, %OI, %Ok, %Ol,
    %Om, %OM, %OS, %Ou, %Ow, %Oy

  
All of these format groups are synonymous with their counterparts without
      the “O”, except that the string is produced and
      parsed in the locale-dependent alternative numerals.

  
%p

  
On output, produces an indicator for the part of the day, AM or
      PM, appropriate to the given locale. If the script of the given
      locale supports multiple letterforms, lowercase is preferred. On input,
      matches the representation AM or PM in the given locale, in
      either case.

  
%P

  
On output, produces an indicator for the part of the day, am or
      pm, appropriate to the given locale. If the script of the given
      locale supports multiple letterforms, uppercase is preferred. On input,
      matches the representation AM or PM in the given locale, in
      either case.

  
%Q

  
This format group is reserved for internal use within the Tcl
    library.

  
%r

  
On output, produces a locale-dependent time of day representation on a
      12-hour clock. On input, accepts whatever %r produces.

  
%R

  
On output, the time in 24-hour notation (%H:%M). For a version including
      the seconds, see %T below. On input, accepts whatever %R
      produces.

  
%s

  
On output, simply formats the timeVal argument as a decimal integer
      and inserts it into the output string. On input, accepts a decimal integer
      and uses is as the time value without any further processing. Since
      %s uniquely determines a point in time, it overrides all other
      input formats.

  
%S

  
On output, produces a two-digit number of the second of the minute
      (00-59). On input, accepts two digits and uses them as the second of the
      minute.

  
%t

  
On output, produces a TAB character. On input, matches a TAB
    character.

  
%T

  
Synonymous with %H:%M:%S.

  
%u

  
On output, produces the number of the day of the week
      (1→Monday, 7→Sunday). On input, accepts a
      single digit and interprets it as the day of the week. Sunday may be
      either 0 or 7.

  
%U

  
On output, produces the ordinal number of the week of the year (00-53).
      The first Sunday of the year is the first day of week 01. On input accepts
      two digits which are otherwise ignored. This format group is never used in
      determining an input date. This interpretation of the week of the year was
      once common in US banking but is now largely obsolete. See %V for
      the ISO8601 week number.

  
%V

  
On output, produces the number of the ISO8601 week as a two digit number
      (01-53). Week 01 is the week containing January 4; or the first week of
      the year containing at least 4 days; or the week containing the first
      Thursday of the year (the three statements are equivalent). Each week
      begins on a Monday. On input, accepts the ISO8601 week number.

  
%w

  
On output, produces the ordinal number of the day of the week (Sunday==0;
      Saturday==6). On input, accepts a single digit and interprets it as the
      day of the week; Sunday may be represented as either 0 or 7. Note that
      %w is not the ISO8601 weekday number, which is produced and
      accepted by %u.

  
%W

  
On output, produces a week number (00-53) within the year; week 01 begins
      on the first Monday of the year. On input, accepts two digits, which are
      otherwise ignored. This format group is never used in determining an input
      date. It is not the ISO8601 week number; that week is produced and
      accepted by %V.

  
%x

  
On output, produces the date in a locale-dependent representation. On
      input, accepts whatever %x produces and is used to determine
      calendar date.

  
%X

  
On output, produces the time of day in a locale-dependent representation.
      On input, accepts whatever %X produces and is used to determine
      time of day.

  
%y

  
On output, produces the two-digit year of the century. On input, accepts
      two digits, and is used to determine calendar date. The date is presumed
      to lie between 1938 and 2037 inclusive. Note that %y does not yield
      a year appropriate for use with the ISO8601 week number %V;
      programs should use %g for that purpose.

  
%Y

  
On output, produces the four-digit calendar year. On input, accepts four
      digits and may be used to determine calendar date. Note that %Y
      does not yield a year appropriate for use with the ISO8601 week number
      %V; programs should use %G for that purpose.

  
%z

  
On output, produces the current time zone, expressed in hours and minutes
      east (+hhmm) or west (-hhmm) of Greenwich. On input, accepts a time zone
      specifier (see TIME ZONES below) that will be used to determine the
      time zone.

  
%Z

  
On output, produces the current time zone's name, possibly translated to
      the given locale. On input, accepts a time zone specifier (see TIME
      ZONES below) that will be used to determine the time zone. This option
      should, in general, be used on input only when parsing RFC822 dates. Other
      uses are fraught with ambiguity; for instance, the string BST may
      represent British Summer Time or Brazilian Standard Time. It is
      recommended that date/time strings for use by computers use numeric time
      zones instead.

  
%%

  
On output, produces a literal “%” character. On
      input, matches a literal “%” character.

  
%+

  
Synonymous with “%a %b %e %H:%M:%S %Z %Y”.








TIME ZONES


When the clock command is processing a local time, it has
    several possible sources for the time zone to use. In order of preference,
    they are:



  
[1]

  
A time zone specified inside a string being parsed and matched by a
      %z or %Z format group.

  
[2]

  
A time zone specified with the -timezone option to the clock
      command (or, equivalently, by -gmt 1).

  
[3]

  
A time zone specified in an environment variable TCL_TZ.

  
[4]

  
A time zone specified in an environment variable TZ.

  
[5]

  
The local time zone from the Control Panel on Windows systems.

  
[6]

  
The C library's idea of the local time zone, as defined by the
      mktime and localtime functions.




In case [1] only, the string is tested to see if it is one
    of the strings:








 gmt     ut      utc     bst     wet     wat     at


 nft     nst     ndt     ast     adt     est     edt


 cst     cdt     mst     mdt     pst     pdt     yst


 ydt     hst     hdt     cat     ahst    nt      idlw


 cet     cest    met     mewt    mest    swt     sst


 eet     eest    bt      it      zp4     zp5     ist


 zp6     wast    wadt    jt      cct     jst     cast


 cadt    east    eadt    gst     nzt     nzst    nzdt


 idle




If it is a string in the above list, it designates a known time
    zone, and is interpreted as such.


For time zones in case [1] that do not match any of the above
    strings, and always for cases [2]-[6], the following rules apply.


If the time zone begins with a colon, it is one of a standardized
    list of names like :America/New_York that give the rules for various
    locales. A complete list of the location names is too lengthy to be listed
    here. On most Tcl installations, the definitions of the locations are to be
    found in named files in the directory
    “/no_backup/tools/lib/tcl8.5/clock/tzdata”. On some
    Unix systems, these files are omitted, and the definitions are instead
    obtained from system files in “/usr/share/zoneinfo”,
    “/usr/share/lib/zoneinfo” or
    “/usr/local/etc/zoneinfo”. As a special case, the name
    :localtime refers to the local time zone as defined by the C
  library.


A time zone string consisting of a plus or minus sign followed by
    four or six decimal digits is interpreted as an offset in hours, minutes,
    and seconds (if six digits are present) from UTC. The plus sign denotes a
    sign east of Greenwich; the minus sign one west of Greenwich.


A time zone string conforming to the Posix specification of the
    TZ environment variable will be recognized. The specification may be
    found at
    http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html.


If the Posix time zone string contains a DST (Daylight Savings
    Time) part, but doesn't contain a rule stating when DST starts or ends, then
    default rules are used. For Timezones with an offset between 0 and +12, the
    current European/Russian rules are used, otherwise the current US rules are
    used. In Europe (offset +0 to +2) the switch to summertime is done each last
    Sunday in March at 1:00 GMT, and the switch back is each last Sunday in
    October at 2:00 GMT. In Russia (offset +3 to +12), the switch dates are the
    same, only the switch to summertime is at 2:00 local time, and the switch
    back is at 3:00 local time in all time zones. The US switch to summertime
    takes place each second Sunday in March at 2:00 local time, and the switch
    back is each first Sunday in November at 3:00 local time. These default
    rules mean that in all European, Russian and US (or compatible) time zones,
    DST calculations will be correct for dates in 2007 and later, unless in the
    future the rules change again.


Any other time zone string is processed by prefixing a colon and
    attempting to use it as a location name, as above.






LOCALIZATION


Developers wishing to localize the date and time formatting and
    parsing are referred to http://tip.tcl.tk/173 for a
  specification.






FREE FORM SCAN


If the clock scan command is invoked without a
    -format option, then it requests a free-form scan. 
    This form of scan is deprecated. The reason for the deprecation is
    that there are too many ambiguities. (Does the string “2000”
    represent a year, a time of day, or a quantity?) No set of rules for
    interpreting free-form dates and times has been found to give unsurprising
    results in all cases.


If free-form scan is used, only the -base and -gmt
    options are accepted. The -timezone and -locale options will
    result in an error if -format is not supplied.


For the benefit of users who need to understand legacy code that
    uses free-form scan, the documentation for how free-form scan interprets a
    string is included here:


If only a time is specified, the current date is assumed. If the
    inputString does not contain a time zone mnemonic, the local time
    zone is assumed, unless the -gmt argument is true, in which case the
    clock value is calculated assuming that the specified time is relative to
    Greenwich Mean Time. -gmt, if specified, affects only the computed
    time value; it does not impact the interpretation of -base.


If the -base flag is specified, the next argument should
    contain an integer clock value. Only the date in this value is used, not the
    time. This is useful for determining the time on a specific day or doing
    other date-relative conversions.


The inputString argument consists of zero or more
    specifications of the following form:



  

  
A time of day, which is of the form: hh?:mm?:ss?? ?meridian? ?zone?
      or hhmm ?meridian? ?zone? If no meridian is specified, hh is
      interpreted on a 24-hour clock.

  

  
A specific month and day with optional year. The acceptable formats are
      “mm/dd?/yy?”, “monthname dd?,
      yy?”, “day, dd monthname ?yy?”,
      “dd monthname yy”,
      “?CC?yymmdd”, and
      “dd-monthname-?CC?yy”. The default year
      is the current year. If the year is less than 100, we treat the years
      00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can
      represent the years 38-70, so an error may result if these years are
    used.

  

  
An ISO 8601 point-in-time specification, such as
      “CCyymmddThhmmss,” where T is
      the literal “T”, “CCyymmdd hhmmss”, or
      “CCyymmddThh:mm:ss”. Note that only
      these three formats are accepted. The command does not accept the
      full range of point-in-time specifications specified in ISO8601. Other
      formats can be recognized by giving an explicit -format option to
      the clock scan command.

  

  
A specification relative to the current time. The format is number
      unit. Acceptable units are year, fortnight,
      month, week, day, hour, minute (or
      min), and second (or sec). The unit can be specified
      as a singular or plural, as in 3 weeks. These modifiers may also be
      specified: tomorrow, yesterday, today, now,
      last, this, next, ago.




The actual date is calculated according to the following
  steps.


First, any absolute date and/or time is processed and converted.
    Using that time as the base, day-of-week specifications are added. Next,
    relative specifications are used. If a date or day is specified, and no
    absolute or relative time is given, midnight is used. Finally, a correction
    is applied so that the correct hour of the day is produced after allowing
    for daylight savings time differences and the correct date is given when
    going from the end of a long month to a short month.






SEE ALSO


msgcat(n)






KEYWORDS


clock, date, time






COPYRIGHT


Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All
    rights reserved.







  

    8.5
    Tcl